This release includes the source code of OpenDoc 1.0.4. The source code is primarily intended for use with source-level debuggers, so that you can step into and trace through OpenDoc code, and .SYM and .xSYM files are provided to assist with this. Reading the source may also help you figure out what particular OpenDoc methods are doing internally, which may help you understand behaviors that are not adequately documented, or might even help you discover bugs in OpenDoc.
The source code is not intended to — or even sufficient to — let you compile OpenDoc. It is missing not only makefiles and project files, but also some IDL files, header files and a very few source files that contain Apple-confidential internal details of system data structures. None of this will hamper your use of the source code for debugging or educational purposes.
We must also caution that you not use the source to uncover undocumented behaviors of OpenDoc — such as undocumented side effects of a method — and then take advantage of those behaviors in your parts. We might change that method in the next release and the undocumented, probably unintentional behavior you were depending on might go away, to your chagrin and that of your customers.
And of course, the source code is copyrighted by Apple Computer. Check the CD license agreement to see what you may legitimately use it and not use it for. (Incorporating any of it into derivative works is right out.)
Using The Source Code For Debugging
Use the installer in this folder to install the debug version of OpenDoc. The debug build has many other fine uses, apart from enabling source-level debugging of OpenDoc itself; see the “Read Me - Debugging Support” document to learn more.
Copy the correct symbol files (.SYM for 68K, .xSYM for PPC) for OpenDocLib and Memory Manager to the same folder as your OpenDoc libraries — the OpenDoc Libraries subfolder of the Extensions folder. For convenience you might make aliases of the sym files and put them in a more accessible spot. (Not all debuggers require that the sym files be in the same locations as the binaries, but the Metrowerks debugger does.)
Now open the appropriate sym file — probably OpenDocLib.SYM or OpenDocLib.xSYM — along with the sym file for your own code, and you'll be able to view and step through OpenDoc source code. The debugger will ask for the location of an OpenDoc source file the first time it needs to view it; just navigate to the “OpenDoc Source Code” folder within this folder on the CD and find the file. (The Metrowerks debugger normally knows the exact path to a source file, but in this case the path to the file on the CD is not the same as the path on our build machine which is written into the sym file, so the automatic lookup fails.) Of course, you can copy the source files or the subset you need to your hard disk if you prefer.
We hope that source-level access to OpenDoc makes your debugging a happier and more productive experience!
